@std/esm
This fast, small, zero-dependency package is all you need to enable
ES modules in Node 4+ today!
See the release post
:book: and video :movie_camera:
for all the details.
Getting started
-
Run npm i --save @std/esm
in your app or package directory.
-
Create the ESM loader to import your main ES module:
index.js
require = require("@std/esm")(module)
module.exports = require("./main.mjs").default
By default, @std/esm
only processes files of packages that opt-in
with a @std/esm
options object or @std/esm
as a dependency, dev
dependency, or peer dependency in their package.json. However, you can
enable processing all files with specific options by passing an options
object as the second argument or passing true
to use the options from
your package.json.
require = require("@std/esm")(module, options)
Enable ESM in the Node CLI with the -r
option:
node -r @std/esm file.mjs
Enable ESM in the Node REPL:
node -r @std/esm
Or upon entering:
$ node
> require("@std/esm")
@std/esm enabled
> import p from "path"
undefined
> p.join("hello", "world")
'hello/world'
Note: The "cjs"
and "gz"
options are unlocked in the Node REPL.
Standard Features
The @std/esm
loader is as spec-compliant
as possible and follows Node’s ESM rules.
:point_right: This means, by default, ESM requires the use of the .mjs
file
extension.
:unlock: You can unlock ESM with the .js
file extension using
the "js"
ESM mode.
Out of the box @std/esm
just works, no configuration necessary, and supports:
Unlockables
Unlock extra features with "@std/esm":options
or "@std":{"esm":options}
in your package.json.
Commonly used options may be specified in shorthand form:
"@std/esm":"js"
is shorthand for "@std/esm":{"esm":"js"}
"@std/esm":"cjs"
is shorthand for "@std/esm":{"cjs":true,"esm":"js"}
{
"@std/esm": {
|
"esm": |
A string ESM mode:
"mjs" files as ESM (default)"all" files as ESM"js" and other files with import , export , or "use module" as ESM
|
"cjs": |
A boolean to unlock CJS features in ESM.
|
"await": |
A boolean to support top-level await in the main ES module.
|
"gz": |
A boolean to support gzipped module (i.e. .js.gz , .mjs.gz ).
Note: Don’t forget the webpack gzip-loader .
|
}
}
|
Cont’d
The "cjs"
option may also be specified as an object.
{
"@std/esm": {
"cjs": {
|
"cache": |
A boolean for storing ES modules in require.cache .
|
"extensions": |
A boolean for respecting require.extensions in ESM.
|
"interop": |
A boolean for __esModule interoperability.
|
"namedExports": |
A boolean to support importing named exports of CJS modules.
|
"paths": |
A boolean for following CJS path rules in ESM.
|
"topLevelReturn": |
A boolean to support top-level return .
|
"vars": |
A boolean to expose __dirname , __filename , and require in ESM.
|
}
}
}
|
DevOpts
{
"@std/esm": {
|
"cache": |
A boolean for toggling .cache creation (default: true ).
|
"debug": |
A boolean for unmasking stack traces.
|
"sourceMap": |
A boolean for including inline source maps.
Note: Automatically enabled using the Node CLI
--inspect option.
|
"warnings": |
A boolean for logging parse and runtime warnings.
(default: process.env.NODE_ENV !== "production" )
|
}
}
|
Tips
- Load
@std/esm
before @babel/register
v7+ - Load
@std/esm
with the “require” option of ava
,
mocha
,
nyc
, and
tape
- Load
@std/esm
with the --node-arg=-r --node-arg=@std/esm
option of node-tap
- Use options
"@std/esm":"cjs"
or "@std/esm":{"cjs":{"cache":true}}
with the Mocha --watch
option - Use options
"@std/esm":"cjs"
with webpack
- When in doubt, use options
"@std/esm":"cjs"